3D Graphics Programming with QuickDraw 3D 1.5.4
Previous | QD3D Book | Overview | Chapter Contents | Next |
Rendering in a View
QuickDraw 3D provides routines that you can use to manage the process of rendering in a view. The view must already exist and be fully configured before you call these routines.
Q3View_StartRendering
You can use the Q3View_StartRendering function to start rendering an image of a model.
TQ3Status Q3View_StartRendering (TQ3ViewObject view);
DESCRIPTION
The Q3View_StartRendering function begins the process of rendering an image of a model in the view specified by the view parameter. After calling Q3View_StartRendering , you specify the model to be drawn (for instance, by calling Q3Geometry_Submit ). When you have completely specified that model, you should call Q3View_EndRendering to complete the rendering of the image. Because the renderer attached to the specified view might need to reprocess the model data, you should always call Q3View_StartRendering and Q3View_EndRendering in a rendering loop.
Calling Q3View_StartRendering automatically clears the buffer into which the rendered image is drawn.
SPECIAL CONSIDERATIONS
You should not call Q3View_StartRendering while rendering is already occurring.
SEE ALSO
See "Rendering an Image" for more information about a rendering loop.
Q3View_EndRendering
You can use the Q3View_EndRendering function to stop rendering an image of a model.
TQ3ViewStatus Q3View_EndRendering (TQ3ViewObject view);
DESCRIPTION
The Q3View_EndRendering function returns, as its function result, a view status value that indicates the current state of the rendering of an image of a model in the view specified by the view parameter. Q3View_EndRendering returns one of these four values:
typedef enum TQ3ViewStatus {
kQ3ViewStatusDone,
kQ3ViewStatusRetraverse,
kQ3ViewStatusError,
kQ3ViewStatusCancelled
} TQ3ViewStatus;
If Q3View_EndRendering returns kQ3ViewStatusDone , the rendering of the image has been completed and the specified view is no longer in rendering mode. At that point, it is safe to exit your rendering loop. If double-buffering is active, the front buffer is updated with the rendered image.
If the renderer associated with the specified view relies on a hardware accelerator for some or all of its operation, Q3View_EndRendering may return kQ3ViewStatusDone even though the rendering has not yet completed. (When a hardware accelerator is present, rendering occurs asynchronously.) If you must know when the rendering has actually finished, call the Q3View_Sync function.
If Q3View_EndRendering returns kQ3ViewStatusRetraverse , the rendering of the image has not yet been completed. You should respecify the model by reentering your rendering loop.
If Q3View_EndRendering returns kQ3ViewStatusError , the rendering of the image has failed because the renderer associated with the view encountered an error in processing the model. You should exit the rendering loop.
If Q3View_EndRendering returns kQ3ViewStatusCancelled , the rendering of the image has been canceled. You should exit the rendering loop.
SEE ALSO
See "Rendering an Image" for a sample rendering loop.
Q3View_Cancel
You can use the Q3View_Cancel function to cancel the rendering, picking, bounding, or writing operation currently occurring in a view.
TQ3Status Q3View_Cancel (TQ3ViewObject view);
DESCRIPTION
The Q3View_Cancel function interrupts the process of rendering an image of a model, submitting objects for picking, calculating a bounding box or sphere, or writing data to a file in accordance with the view specified by the view parameter. Any subsequent calls to _Submit routines for the specified view will fail, and Q3View_EndRendering (or the similar call for picking, bounding, or writing) will return kQ3ViewStatusCancelled when it is next executed. Note that you must still call Q3View_EndRendering (or the similar call for picking, bounding, or writing) after you have called Q3View_Cancel .
You can call Q3View_Cancel at any time. If the specified view is not in the submitting state, Q3View_Cancel returns kQ3Failure .
Q3View_Flush
You can use the Q3View_Flush function to flush buffered graphics to a rasterizer.
TQ3Status Q3View_Flush (TQ3ViewObject view);
DESCRIPTION
The Q3View_Flush function is a non-blocking call that flushes all buffered graphics to a rasterizer (if one is implemented). It may or may not update the draw context, depending on the type of renderer. The Q3View_Flush function may be called only between calls to Q3View_StartRendering and Q3View_EndRendering .
Q3View_Sync
You can use the Q3View_Sync function to flush buffered graphics to a rasterizer and also update the draw context.
TQ3Status Q3View_Sync (TQ3ViewObject view);
© 1997 Apple Computer, Inc.
Previous | QD3D Book | Overview | Chapter Contents | Next |